Event Notification API

2.0.x
(0 reviews)

Event Notification Payload Signing

Payload Signing

This section provides steps for signing the payload and generating a valid x-jws-signature.

Step 1: Identify the private key and corresponding signing certificate to be used for signing

The signer must use a private key that has a corresponding digital certificate (that contains the corresponding public key) issued by OB. The signing
certificate must be valid at the time of creating the JWS.

Step 2: Form the JOSE Header

The JOSE Header for the signature must contain the following fields

ClaimDescription
    alg The algorithm that will be used for signing the JWS.

The list of valid algorithms is here https://tools.ietf.org/html/rfc7518#section-3.1.

This value must be PS256
    typ This is an optional claim.

If it is specified, it must be set to the value JOSE.
    cty This is an optional claim for JSON payloads

If it is specified, it must be set to the value json or application/json for json payloads.

For non-json payloads (e.g. for PDF files), the mime type of the payload must be specified in this claim.
    kid This is a mandatory claim.

It must match a value that can be used to look up the key in a key store hosted by the Trust Anchor.
http://openbanking.org.uk/iat This must be a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in GMT until the date/time.

This is a private header parameter name. (See RFC 7515 - Private Header Parameter Names (opens new window))
http://openbanking.org.uk/iss This must be a string that identifies the PSP.

If the issuer is using a certificate this value must match the subject of the signing certificate.

If the issuer is using a signing key lodged with a Trust Anchor, the value is defined by the Trust Anchor and should uniquely identify the PSP.

For example, when using the Open Banking Directory, the value must be:

  • When issued by a TPP, of the form {{org-id}}/{{software-statement-id}},
  • When issued by an ASPSP of the form {{org-id}}

Where :

  • org-id is the open-banking issued organization id
  • software-statement-id is the open-banking issued software-statement-id
http://openbanking.org.uk/tan This must be a string that consists of a domain name that is registered to and identifies the Trust Anchor that hosts the public counter-part of the key used for signing.

For example, when using the Open Banking Directory, the value must be openbanking.org.uk
    crit This must be a string array consisting of the values http://openbanking.org.uk/iat, http://openbanking.org.uk/iss, http://openbanking.org.uk/tan

This indicates that the JWS signature validator must understand and process the three additional claims.

Sample JOSE Header

{
  "http://openbanking.org.uk/iat": 1649054097,
  "http://openbanking.org.uk/tan": "openbanking.org.uk",
  "crit": [
    "http://openbanking.org.uk/iat",
    "http://openbanking.org.uk/tan",
    "http://openbanking.org.uk/iss"
  ],
  "kid": "65Zw6tUOAuz4Cq9KA1rrqXwUK7A",
  "cty": "application/json",
  "typ": "JOSE",
  "http://openbanking.org.uk/iss": "CN=0015800000jfQ9aAAE, OID.2.5.4.97=PSDGB-FCA-512956, O=Bank of Ireland (UK) Plc, C=GB",
  "alg": "PS256"
}

Step 3: Compute the JWS

The signer must compute the signature as a detached JWS as defined in RFC 7515.
detachedJWS = base64Encode( JOSEHeader) + ".." + base64Encode ( encrypt (privateKey, base64Encode(json)))

Step 4: Add the JWS as a HTTP header

The signer must include an HTTP header called x-jws-signature with its value set to the signature computed in Step 3.

x-jws-signature: eyJodHRwOlwvXC9vcGVuYmFua2luZy5vcmcudWtcL2lhdCI6MTY0OTA1NDA5NywiaHR0cDpcL1wvb3BlbmJhbmtpbmcub3JnLnVrXC90YW4iOiJvcGVu
YmFua2luZy5vcmcudWsiLCJjcml0IjpbImh0dHA6XC9cL29wZW5iYW5raW5nLm9yZy51a1wvaWF0IiwiaHR0cDpcL1wvb3BlbmJhbmtpbmcub3JnLnVrXC90YW4iLCJodHRwO
lwvXC9vcGVuYmFua2luZy5vcmcudWtcL2lzcyJdLCJraWQiOiI2NVp3NnRVT0F1ejRDcTlLQTFycnFYd1VLN0EiLCJjdHkiOiJhcHBsaWNhdGlvblwvanNvbiIsInR5cCI6Ikp
PU0UiLCJodHRwOlwvXC9vcGVuYmFua2luZy5vcmcudWtcL2lzcyI6IkNOPTAwMTU4MDAwMDBqZlE5YUFBRSwgT0lELjIuNS40Ljk3PVBTREdCLUZDQS01MTI5NTYsIE89QmFua
yBvZiBJcmVsYW5kIChVSykgUGxjLCBDPUdCIiwiYWxnIjoiUFMyNTYifQ..sm5DgQ0twHU3XvJtqzpTgy5pE0r75DZukWWqrBwXoD8bqnRHni_tswnRnZpuMZgjuhRDkzkFtiI
k_aVCVERvGN9qgLQUzvLD9hEXTA9b6VmqTDKrM62qOSsKjYdnSa1DCD0E_wg0JWt-9EN92Fl9UmbnXxQ3JR0TjNOI-Q9zbFaom4xwBWftXqAVutg_Ow4GJN24IiGw6gS1cNIQ1K
B3jbW-O2h4QyJGhlfHtIYGJPeZOwj_O5yKpk6Aqku-EFDpo00awZPbRWhTPAmJfVqQZitliyKa5zx2cr0PE8cR09VANRz8fa6URH4bfvoh1udpMMbNWHbO5ND_lSUjjXyrJw

Reviews

Reviews